Skip to content

feat: add host-visible integration diagnostics - #1360

Merged
Teingi merged 17 commits into
oceanbase:masterfrom
Alanxtl:step1
Sep 2, 2026
Merged

Teingi merged 17 commits into
oceanbase:masterfrom
Alanxtl:step1

Conversation

@Alanxtl

@Alanxtl Alanxtl commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator

Which issue or RFC does this PR close?

This PR implements the first step of #1298. It does not close #1298.

This PR is downstream of #1343 and should be reviewed after #1343 is merged.

Rationale for this change

When PowerContext is unavailable or returns an incompatible response, integrations currently provide limited or inconsistent feedback. Users need a bounded, fail-open diagnostic that explains the failure and points to powercontext doctor without exposing request details or disrupting the host.

What changes are included in this PR?

  • Add common failure classification:
    • authentication_failed
    • version_mismatch
    • server_unavailable
    • invalid_response
  • Add host-visible diagnostics for:
Host Diagnostic channel Component
Codex Hook stderr powercontext.codex.recall
Claude Code Hook stderr powercontext.claude_code.recall
DSH Host logger warning powercontext.dsh
OpenClaw Plugin logger warning powercontext.openclaw
Pi Host terminal warning powercontext.pi
Hermes Python host logger warning powercontext.hermes
  • Use each host’s supported logging/output channel.
  • Add 60-second deduplication to avoid repeated warnings.
  • Keep integrations fail-open and content-free.
  • Preserve generic tool errors for model-facing responses.
  • Add the powercontext doctor recovery hint for unavailable servers.
  • Update troubleshooting documentation and integration tests.
  • Bub is out of scope for this PR.

Are there any user-facing changes?

Yes.

Users now receive a bounded diagnostic when PowerContext is unavailable or returns a classified failure. Normal host execution continues, and no URL, token, response body, or user content is included in the diagnostic.

There are no breaking API or persistence-format changes.

How was this change tested?

  • uv run pytest tests/integrations/test_hermes_provider.py -q — 36 passed
  • uv run ruff check integrations/hermes/plugins/powercontext/commands.py tests/integrations/test_hermes_provider.py — passed
  • Codex and Claude Code diagnostic tests passed
  • Pi and OpenClaw lifecycle diagnostic tests passed
  • DSH bundled output passed node --check
  • Manual validation with an unreachable PowerContext endpoint confirmed fail-open behavior and generic tool errors.
  • Verified diagnostic deduplication and powercontext doctor recovery metadata.

AI usage statement

Implemented and reviewed with OpenAI Codex

@Teingi
Teingi merged commit debb838 into oceanbase:master Sep 2, 2026
13 checks passed
tlyyxjz added a commit to tlyyxjz/ob2026-powercontext that referenced this pull request Oct 9, 2026
…g treats as domain

Both from @AlexStocks' review of oceanbase#1883.

The 400 branch added by this PR could not name the real condition, because the code the
Server sends there was still unpublished: `invalid_cursor` was absent from
`PUBLIC_ERROR_CODES`, so the branch collapsed it to `invalid_request`. That is the same
defect the previous commit fixed for 410, 428 and 429, and `invalid_cursor` is the 400 half
of the cursor pair — RFC 1502 says "return `400 invalid_cursor`; expired cursors return
`410 cursor_expired`". Both are published now, and the 400 result carries the cursor
recovery rather than "fix the request shape", because the two conditions call for
different actions. Only this code was reachable: `distinct_scopes_required` can also
follow a 400, but its sole raise site passes `field="scope_id"`, which routes to 422.

`isDomainStatus` still listed 404, 409 and 422, the three statuses the mapping had a branch
for when oceanbase#1360 introduced it. The mapping now gives 400, 410, 412, 413, 428 and 429 their
own branches as domain outcomes too, so the diagnostic layer withheld a diagnostic for a
409 while logging one for a 412 — the same class of rejection, two behaviours. The set is
now `DOMAIN_STATUSES`, and `tests/error-mapping.spec.ts` asserts it against the statuses
`mapServerError` branches on plus 401/403, so the two layers cannot drift apart again.

`pnpm test` 309 passed / 1 skipped (305 before), `lib/` rebuilt, and the result-code table
in both integration guides lists `invalid_cursor`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tracking Issue: local Server availability and service installation

1 participant